home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / DigitalSignature.a < prev    next >
Text File  |  1996-05-01  |  18KB  |  495 lines
  1. ;
  2. ;    File:        DigitalSignature.a
  3. ;
  4. ;    Contains:    Digital Signature Interfaces.
  5. ;
  6. ;    Version:    Technology:    AOCE toolbox 1.02
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__DIGITALSIGNATURE__') = 'UNDEFINED' THEN
  19. __DIGITALSIGNATURE__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF &TYPE('__MEMORY__') = 'UNDEFINED' THEN
  25.     include 'Memory.a'
  26.     ENDIF
  27.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  28.     include 'Files.a'
  29.     ENDIF
  30.     IF FOR_SYSTEM7_ONLY THEN
  31. ;  values of SIGNameAttributeType 
  32.  
  33. kSIGCountryCode                    EQU        0
  34. kSIGOrganization                EQU        1
  35. kSIGStreetAddress                EQU        2
  36. kSIGState                        EQU        3
  37. kSIGLocality                    EQU        4
  38. kSIGCommonName                    EQU        5
  39. kSIGTitle                        EQU        6
  40. kSIGOrganizationUnit            EQU        7
  41. kSIGPostalCode                    EQU        8
  42. ; typedef unsigned short                 SIGNameAttributeType
  43.  
  44. ;
  45. ;Certificate status codes returned in SIGCertInfo or SIGSignerInfo from
  46. ;either SIGGetCertInfo or SIGGetSignerInfo respectively. kSIGValid means that
  47. ;the certificate is currently valid. kSIGPending means the certificate is
  48. ;currently not valid - but will be.  kSIGExpired means the certificate has
  49. ;expired. A time is always associated with a SIGCertStatus.  In each case the
  50. ;time has a specific interpretation.  When the status is kSIGValid the time is
  51. ;when the certificate will expire. When the status is kSIGPending the time is
  52. ;when the certificate will become valid. When the status is kSIGExpired the time
  53. ;is when the certificate expired. In the SIGCertInfo structure, the startDate
  54. ;and endDate fields hold the appropriate date information.  In the SIGSignerInfo
  55. ;structure, this information is provided in the certSetStatusTime field. In the
  56. ;SIGSignerInfo struct, the status time is actually represented by the SIGSignatureStatus
  57. ;field which can contain any of the types below. NOTE: The only time you will get 
  58. ;a kSIGInvalid status is when it pertains to a SIGSignatureStatus field and only when
  59. ;you get a signature that was created after the certificates expiration date, something
  60. ;we are not allowing on the Mac but that may not be restricted on other platforms. Also, 
  61. ;it will not be possible to get a kSIGPending value for SIGSignatureStatus on the Mac but
  62. ;possibly allowed by other platforms.
  63. ;
  64. ;  Values for SIGCertStatus or SIGSignatureStatus 
  65.  
  66. kSIGValid                        EQU        0                    ; possible for either a SIGCertStatus or SIGSignatureStatus 
  67. kSIGPending                        EQU        1                    ; possible for either a SIGCertStatus or SIGSignatureStatus 
  68. kSIGExpired                        EQU        2                    ; possible for either a SIGCertStatus or SIGSignatureStatus * possible only for a SIGSignatureStatus 
  69. kSIGInvalid                        EQU        3
  70. ; typedef unsigned short                 SIGCertStatus
  71.  
  72. ; typedef unsigned short                 SIGSignatureStatus
  73.  
  74. ;  Gestalt selector code - returns toolbox version in low-order word 
  75.  
  76. gestaltDigitalSignatureVersion    EQU        'dsig'
  77. ;  Number of bytes needed for a digest record when using SIGDigest 
  78.  
  79. kSIGDigestSize                    EQU        16
  80. SIGDigestData            RECORD 0
  81. elements                 ds.b    16
  82. sizeof                     EQU *                    ; size:   $10 (16)
  83.                         ENDR
  84.  
  85.  
  86. ; typedef Byte *                        SIGDigestDataPtr
  87.  
  88. SIGCertInfo                RECORD 0
  89. startDate                 ds.l    1                ; offset: $0 (0)        ;  cert start validity date 
  90. endDate                     ds.l    1                ; offset: $4 (4)        ;  cert end validity date 
  91. certStatus                 ds.w    1                ; offset: $8 (8)        ;  see comment on SIGCertStatus for definition 
  92. certAttributeCount         ds.l    1                ; offset: $A (10)        ;  number of name attributes in this cert 
  93. issuerAttributeCount     ds.l    1                ; offset: $E (14)        ;  number of name attributes in this certs issuer 
  94. serialNumber             ds        Str255            ; offset: $12 (18)        ;  cert serial number 
  95. sizeof                     EQU *                    ; size:   $112 (274)
  96.                         ENDR
  97. ; typedef struct SIGCertInfo *            SIGCertInfoPtr
  98.  
  99. SIGSignerInfo            RECORD 0
  100. signingTime                 ds.l    1                ; offset: $0 (0)        ;  time of signing 
  101. certCount                 ds.l    1                ; offset: $4 (4)        ;  number of certificates in the cert set 
  102. certSetStatusTime         ds.l    1                ; offset: $8 (8)        ;  Worst cert status time. See comment on SIGCertStatus for definition 
  103. signatureStatus             ds.w    1                ; offset: $C (12)        ;  The status of the signature. See comment on SIGCertStatus for definition
  104. sizeof                     EQU *                    ; size:   $E (14)
  105.                         ENDR
  106. ; typedef struct SIGSignerInfo *        SIGSignerInfoPtr
  107.  
  108. SIGNameAttributesInfo    RECORD 0
  109. onNewLevel                 ds.b    1                ; offset: $0 (0)
  110. filler1                     ds.b    1                ; offset: $1 (1)
  111. attributeType             ds.w    1                ; offset: $2 (2)
  112. attributeScript             ds.w    1                ; offset: $4 (4)
  113. attribute                 ds        Str255            ; offset: $6 (6)
  114. sizeof                     EQU *                    ; size:   $106 (262)
  115.                         ENDR
  116. ; typedef struct SIGNameAttributesInfo * SIGNameAttributesInfoPtr
  117.  
  118. ; typedef Ptr                             SIGContextPtr
  119.  
  120. ; typedef Ptr                             SIGSignaturePtr
  121.  
  122. ;
  123. ;Certificates are always in order. That is, the signers cert is always 0, the
  124. ;issuer of the signers cert is always 1 etc... to the number of certificates-1.
  125. ;You can use this constant for readability in your code.
  126. ;
  127.  
  128. kSIGSignerCertIndex                EQU        0
  129. ;
  130. ;Call back procedure supplied by developer, return false to cancel the current
  131. ;process.
  132. ;
  133. ;
  134. ;Resource id's of standard signature icon suite, all sizes and colors are available.
  135. ;
  136.  
  137. kSIGSignatureIconResID            EQU        -16797
  138. kSIGValidSignatureIconResID        EQU        -16799
  139. kSIGInvalidSignatureIconResID    EQU        -16798
  140. ;
  141. ; -------------------------------------------------------------- CONTEXT CALLS -------------------------------------------------------------- 
  142. ;To use the Digital Signature toolbox you will need a SIGContextPtr.  To create
  143. ;a SIGContextPtr you simply call SIGNewContext and it will create and initialize
  144. ;a context for you.  To free the memory occupied by the context and invalidate
  145. ;its internal data, call SIGDisposeContext. An initialized context has no notion
  146. ;of the type of operation it will be performing however, once you call
  147. ;SIGSignPrepare SIGVerifyPrepare, or SIGDigestPrepare, the contexts operation
  148. ;type is set and to switch  to another type of operation will require creating a
  149. ;new context. Be sure to pass the same context to corresponding toolbox calls
  150. ;(ie SIGSignPrepare, SIGProcessData, SIGSign)  in other words mixing lets say
  151. ;signing and verify calls with the same context is not allowed.
  152. ;
  153. ;
  154. ; pascal OSErr SIGNewContext(SIGContextPtr *context)
  155. ;
  156.     IF ¨ GENERATINGCFM THEN
  157.         Macro
  158.         _SIGNewContext
  159.             move.l              #$0002076C,D0
  160.             dc.w                $AA5D
  161.         EndM
  162.     ELSE
  163.         IMPORT_CFM_FUNCTION SIGNewContext
  164.     ENDIF
  165.  
  166. ;
  167. ; pascal OSErr SIGDisposeContext(SIGContextPtr context)
  168. ;
  169.     IF ¨ GENERATINGCFM THEN
  170.         Macro
  171.         _SIGDisposeContext
  172.             move.l              #$0002076D,D0
  173.             dc.w                $AA5D
  174.         EndM
  175.     ELSE
  176.         IMPORT_CFM_FUNCTION SIGDisposeContext
  177.     ENDIF
  178.  
  179. ;
  180. ; -------------------------------------------------------------- SIGNING CALLS -------------------------------------------------------------- 
  181. ;Once you have created a SIGContextPtr, you create a signature by calling
  182. ;SIGSignPrepare once, followed by n calls to SIGProcessData, followed by one call
  183. ;toRcpt SIGSign. To create another signature on different data but for the same
  184. ;signer, don't dispose of the context and call SIGProcessData for the new data
  185. ;followed by a call SIGSign again. In this case the signer will not be prompted
  186. ;for their signer and password again as it was already provided.  Once you call
  187. ;SIGDisposeContext, all signer information will be cleared out of the context and
  188. ;the signer will be re-prompted.  The signer file FSSpecPtr should be set to nil
  189. ;if you want the toolbox to use the last signer by default or prompt for a signer
  190. ;if none exists.  The prompt parameter can be used to pass a string to be displayed
  191. ;in the dialog that prompts the user for their password.  If the substring "^1"
  192. ;(without the quotes) is in the prompt string, then the toolbox will replace it
  193. ;with the name of the signer from the signer selected by the user.  If an empty
  194. ;string is passed, the following default string will be sent to the toolbox
  195. ;"\pSigning as ^1.".  You can call any of the utility routines after SIGSignPrepare
  196. ;or SIGSign to get information about the signer or certs.
  197. ;
  198. ;
  199. ; pascal OSErr SIGSignPrepare(SIGContextPtr context, const FSSpec *signerFile, ConstStr255Param prompt, Size *signatureSize)
  200. ;
  201.     IF ¨ GENERATINGCFM THEN
  202.         Macro
  203.         _SIGSignPrepare
  204.             move.l              #$0008076E,D0
  205.             dc.w                $AA5D
  206.         EndM
  207.     ELSE
  208.         IMPORT_CFM_FUNCTION SIGSignPrepare
  209.     ENDIF
  210.  
  211. ;
  212. ; pascal OSErr SIGSign(SIGContextPtr context, SIGSignaturePtr signature, SIGStatusProcPtr statusProc)
  213. ;
  214.     IF ¨ GENERATINGCFM THEN
  215.         Macro
  216.         _SIGSign
  217.             move.l              #$0006076F,D0
  218.             dc.w                $AA5D
  219.         EndM
  220.     ELSE
  221.         IMPORT_CFM_FUNCTION SIGSign
  222.     ENDIF
  223.  
  224. ;
  225. ; -------------------------------------------------------------- VERIFYING CALLS -------------------------------------------------------------- 
  226. ;Once you have created a SIGContextPtr, you verify a signature by calling
  227. ;SIGVerifyPrepare  once, followed by n calls to SIGProcessData, followed by one
  228. ;call to SIGVerify. Check the return code from SIGVerify to see if the signature
  229. ;verified or not (noErr is returned on  success otherwise the appropriate error
  230. ;code).  Upon successfull verification, you can call any of the utility routines
  231. ;toRcpt find out who signed the data.
  232. ;
  233. ;
  234. ; pascal OSErr SIGVerifyPrepare(SIGContextPtr context, SIGSignaturePtr signature, Size signatureSize, SIGStatusProcPtr statusProc)
  235. ;
  236.     IF ¨ GENERATINGCFM THEN
  237.         Macro
  238.         _SIGVerifyPrepare
  239.             move.l              #$00080770,D0
  240.             dc.w                $AA5D
  241.         EndM
  242.     ELSE
  243.         IMPORT_CFM_FUNCTION SIGVerifyPrepare
  244.     ENDIF
  245.  
  246. ;
  247. ; pascal OSErr SIGVerify(SIGContextPtr context)
  248. ;
  249.     IF ¨ GENERATINGCFM THEN
  250.         Macro
  251.         _SIGVerify
  252.             move.l              #$00020771,D0
  253.             dc.w                $AA5D
  254.         EndM
  255.     ELSE
  256.         IMPORT_CFM_FUNCTION SIGVerify
  257.     ENDIF
  258.  
  259. ;
  260. ; ------------------------------------------------------------ DIGESTING CALLS ------------------------------------------------------------ 
  261. ;Once you have created a SIGContextPtr, you create a digest by calling
  262. ;SIGDigestPrepare once, followed by n calls to SIGProcessData, followed by one
  263. ;call to SIGDigest.  You can dispose of the context after SIGDigest as the
  264. ;SIGDigestData does not reference back into it.  SIGDigest returns the digest in
  265. ;digest.
  266. ;
  267. ;
  268. ; pascal OSErr SIGDigestPrepare(SIGContextPtr context)
  269. ;
  270.     IF ¨ GENERATINGCFM THEN
  271.         Macro
  272.         _SIGDigestPrepare
  273.             move.l              #$00020772,D0
  274.             dc.w                $AA5D
  275.         EndM
  276.     ELSE
  277.         IMPORT_CFM_FUNCTION SIGDigestPrepare
  278.     ENDIF
  279.  
  280. ;
  281. ; pascal OSErr SIGDigest(SIGContextPtr context, SIGDigestData digest)
  282. ;
  283.     IF ¨ GENERATINGCFM THEN
  284.         Macro
  285.         _SIGDigest
  286.             move.l              #$00040773,D0
  287.             dc.w                $AA5D
  288.         EndM
  289.     ELSE
  290.         IMPORT_CFM_FUNCTION SIGDigest
  291.     ENDIF
  292.  
  293. ;
  294. ; ------------------------------------------------------------ PROCESSING DATA ------------------------------------------------------------ 
  295. ;To process data during a digest, sign, or verify operation call SIGProcessData
  296. ;as many times as necessary and with any sized blocks of data.  The data needs to
  297. ;be processed in the same order during corresponding sign and verify operations
  298. ;but does not need to be processed in the same sized chunks (i.e., the toolbox
  299. ;just sees it as a continuous bit stream).
  300. ;
  301. ;
  302. ; pascal OSErr SIGProcessData(SIGContextPtr context, const void *data, Size dataSize)
  303. ;
  304.     IF ¨ GENERATINGCFM THEN
  305.         Macro
  306.         _SIGProcessData
  307.             move.l              #$00060774,D0
  308.             dc.w                $AA5D
  309.         EndM
  310.     ELSE
  311.         IMPORT_CFM_FUNCTION SIGProcessData
  312.     ENDIF
  313.  
  314. ;
  315. ; -------------------------------------------------------------- UTILITY CALLS -------------------------------------------------------------- 
  316. ;Given a context that has successfully performed a verification SIGShowSigner
  317. ;will  display a modal dialog with the entire distinguished name of the person
  318. ;who signed the data. the prompt (if supplied) will appear at the top of the
  319. ;dialog.  If no prompt is specified, the default prompt "\pVerification
  320. ;Successfull." will appear.
  321. ;
  322. ;Given a context that has been populated by calling SIGSignPrepare, SIGSign or a
  323. ;successful SIGVerify, you can make the remaining utility calls:
  324. ;
  325. ;SIGGetSignerInfo will return the SignerInfo record.  The certCount can be used
  326. ;toRcpt index into the certificate set when calling SIGGetCertInfo,
  327. ;SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes. The signingTime is
  328. ;only defined if the call is made after SIGSign  or SIGVerify. The certSetStatus
  329. ;will tell you the best status of the entire certificate set while
  330. ;certSetStatusTime will correspond to the time associated with that status (see
  331. ;definitions above).
  332. ;
  333. ;SIGGetCertInfo will return the SIGCertInfo record when given a valid index into
  334. ;the cert set in  certIndex.  Note: The cert at index kSIGSignerCertIndex is
  335. ;always the signers certificate.  The  serial number, start date and end date
  336. ;are there should you wish to display that info.  The  certAttributeCount and
  337. ;issuerAttributeCount provide the number of parts in the name of that certificate
  338. ;or that certificates issuer respectively.  You use these numbers to index into
  339. ;either SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes to retrieve
  340. ;the name. The certStatus will tell you the status of the certificate while
  341. ;certStatusTime will correspond to the time associated with that status (see
  342. ;definitions above).
  343. ;
  344. ;SIGGetCertNameAttributes and SIGGetCertIssuerNameAttributes return name parts
  345. ;of the certificate at  certIndex and attributeIndex.  The newLevel return value
  346. ;tells you wether the name attribute returned is at the same level in the name
  347. ;hierarchy as the previous attribute.  The type return value tells you  the type
  348. ;of attribute returned. nameAttribute is the actual string containing the name
  349. ;attribute.   So, if you wanted to display the entire distinguished name of the
  350. ;person who's signature was just validated you could do something like this;
  351. ;
  352. ;    (...... variable declarations and verification code would preceed this sample ......)
  353. ;
  354. ;    error = SIGGetCertInfo(verifyContext, kSIGSignerCertIndex, &certInfo);
  355. ;    HandleErr(error);
  356. ;
  357. ;    for (i = 0; i <= certInfo.certAttributeCount-1; i++)
  358. ;        {
  359. ;        error = SIGGetCertNameAttributes(
  360. ;            verifyContext, kSIGSignerCertIndex, i, &newLevel, &type, theAttribute);
  361. ;        HandleErr(error);
  362. ;        DisplayNamePart(theAttribute, type, newLevel);
  363. ;        }
  364. ;
  365. ;
  366. ; pascal OSErr SIGShowSigner(SIGContextPtr context, ConstStr255Param prompt)
  367. ;
  368.     IF ¨ GENERATINGCFM THEN
  369.         Macro
  370.         _SIGShowSigner
  371.             move.l              #$00040775,D0
  372.             dc.w                $AA5D
  373.         EndM
  374.     ELSE
  375.         IMPORT_CFM_FUNCTION SIGShowSigner
  376.     ENDIF
  377.  
  378. ;
  379. ; pascal OSErr SIGGetSignerInfo(SIGContextPtr context, SIGSignerInfo *signerInfo)
  380. ;
  381.     IF ¨ GENERATINGCFM THEN
  382.         Macro
  383.         _SIGGetSignerInfo
  384.             move.l              #$00040776,D0
  385.             dc.w                $AA5D
  386.         EndM
  387.     ELSE
  388.         IMPORT_CFM_FUNCTION SIGGetSignerInfo
  389.     ENDIF
  390.  
  391. ;
  392. ; pascal OSErr SIGGetCertInfo(SIGContextPtr context, unsigned long certIndex, SIGCertInfo *certInfo)
  393. ;
  394.     IF ¨ GENERATINGCFM THEN
  395.         Macro
  396.         _SIGGetCertInfo
  397.             move.l              #$00060777,D0
  398.             dc.w                $AA5D
  399.         EndM
  400.     ELSE
  401.         IMPORT_CFM_FUNCTION SIGGetCertInfo
  402.     ENDIF
  403.  
  404. ;
  405. ; pascal OSErr SIGGetCertNameAttributes(SIGContextPtr context, unsigned long certIndex, unsigned long attributeIndex, SIGNameAttributesInfo *attributeInfo)
  406. ;
  407.     IF ¨ GENERATINGCFM THEN
  408.         Macro
  409.         _SIGGetCertNameAttributes
  410.             move.l              #$00080778,D0
  411.             dc.w                $AA5D
  412.         EndM
  413.     ELSE
  414.         IMPORT_CFM_FUNCTION SIGGetCertNameAttributes
  415.     ENDIF
  416.  
  417. ;
  418. ; pascal OSErr SIGGetCertIssuerNameAttributes(SIGContextPtr context, unsigned long certIndex, unsigned long attributeIndex, SIGNameAttributesInfo *attributeInfo)
  419. ;
  420.     IF ¨ GENERATINGCFM THEN
  421.         Macro
  422.         _SIGGetCertIssuerNameAttributes
  423.             move.l              #$00080779,D0
  424.             dc.w                $AA5D
  425.         EndM
  426.     ELSE
  427.         IMPORT_CFM_FUNCTION SIGGetCertIssuerNameAttributes
  428.     ENDIF
  429.  
  430. ;
  431. ; ------------------------------------------------------ FILE SIGN & VERIFY CALLS ---------------------------------------------------- 
  432. ;These calls allow you to detect the presence of a standard signtaure in a file as 
  433. ;well as sign and verify files in a standard way.  An example of this is the Finder, 
  434. ;which uses these calls to allow the user to "drop sign" a file.
  435. ;
  436. ;To detect if a file is signed in the standard way, pass the FSSpec of the file to SIGFileIsSigned.
  437. ;A result of noErr means the file is in fact signed, otherwise, a kSIGNoSignature error will
  438. ;be returned.
  439. ;
  440. ;Once you have created a SIGContextPtr, you can make calls to either sign or verify a file in
  441. ;a standard way: 
  442. ;
  443. ;To sign a file, call SIGSignPrepare followed by 'n' number of calls to SIGSignFile,
  444. ;passing it the file spec for each file you wish to sign in turn.  You supply the context, the signature 
  445. ;size that was returned from SIGSignPrepare and an optional call back proc.  The call will take care of all
  446. ;the processing of data and affixing the signature to the file. If a signature already exists in the file, 
  447. ;it is replaced with the newly created signature.
  448. ;
  449. ;To verify a file that was signed using SIGSignFile, call SIGVerifyFile passing it a new context and 
  450. ;the file spec.  Once this call has completed, if the verification is successfull, you can pass the context 
  451. ;to SIGShowSigner to display the name of the person who signed the file.
  452. ;
  453. ;
  454. ; pascal OSErr SIGFileIsSigned(const FSSpec *fileSpec)
  455. ;
  456.     IF ¨ GENERATINGCFM THEN
  457.         Macro
  458.         _SIGFileIsSigned
  459.             move.l              #$000209C4,D0
  460.             dc.w                $AA5D
  461.         EndM
  462.     ELSE
  463.         IMPORT_CFM_FUNCTION SIGFileIsSigned
  464.     ENDIF
  465.  
  466. ;
  467. ; pascal OSErr SIGSignFile(SIGContextPtr context, Size signatureSize, const FSSpec *fileSpec, SIGStatusProcPtr statusProc)
  468. ;
  469.     IF ¨ GENERATINGCFM THEN
  470.         Macro
  471.         _SIGSignFile
  472.             move.l              #$000809C5,D0
  473.             dc.w                $AA5D
  474.         EndM
  475.     ELSE
  476.         IMPORT_CFM_FUNCTION SIGSignFile
  477.     ENDIF
  478.  
  479. ;
  480. ; pascal OSErr SIGVerifyFile(SIGContextPtr context, const FSSpec *fileSpec, SIGStatusProcPtr statusProc)
  481. ;
  482.     IF ¨ GENERATINGCFM THEN
  483.         Macro
  484.         _SIGVerifyFile
  485.             move.l              #$000609C6,D0
  486.             dc.w                $AA5D
  487.         EndM
  488.     ELSE
  489.         IMPORT_CFM_FUNCTION SIGVerifyFile
  490.     ENDIF
  491.  
  492.     ENDIF
  493.     ENDIF ; __DIGITALSIGNATURE__ 
  494.  
  495.